Installation¶
We recommend to use Linux operating systems to run Smuthi. Otherwise, Smuthi can run on Windows, too, but issues regarding dependencies or performance are more likely.
Installing Smuthi under Ubuntu (recommended)¶
Prerequisites¶
python3 with pip, gfortran and gcc usually are shipped with the operating system. However, Smuthi requires a Python version of 3.6 or newer. Check the installed Python version by:
python3 --version
If the version is 3.5 or less, please install a newer Python version. You can have multiple Python versions installed in parallel. Depending on your configuration, you might need to replace the command python3
in the below by the command that belongs to the newly installed Python, e.g. python3.8
.
Make sure that the Foreign Function Interface library is available (needed for pywigxjpf):
sudo apt-get install libffi6 libffi-dev
Installation¶
To install Smuthi from PyPi, simply type:
sudo python3 -m pip install smuthi
Alternatively, you can install it locally from source (see below section Installing Smuthi from source).
Installing Smuthi under Windows¶
Prerequisites¶
First make sure that a 64 Bit Python 3.6 or newer is installed on your computer. You can install for example Anaconda or WinPython to get a full Python environment.
Warning
Anaconda users are required to update numpy to the latest version from conda-forge before intalling Smuthi. It is also recommended to create a dedicated conda environment for the Smuthi installation. In case the environment gets messed up by destructive interference between Pip and conda, the main Anaconda installation is then still unaffected.
Installation¶
Open a command window and type:
python -m pip install smuthi
Depending on where pip will install the package, you might need administrator rights for that.
Alternatively, install locally from source (see below section Installing Smuthi from source).
Installing Smuthi from source¶
This option allows to install a non-release version of Smuthi or to modify the source code and then run your custom version of Smuthi.
Ubuntu¶
Clone Smuthi and install it locally by:
git clone https://gitlab.com/AmosEgel/smuthi.git
cd smuthi/
sudo python3 -m pip install -e .
Windows¶
Local installation requires a Fortran compiler. Visit the MinGW getting started page and follow the instructions to install gfortran. Make sure to add the bin folder of your MinGW installation to the Windows PATH variable. See Environment Settings section of the MinGW getting started page for instructions.
Note
The MinGW version needs to fit to your Python installation. If you have 64 Bit Python, make sure to download a Mingw-64
Then, download or git clone the Smuthi project folder from the gitlab repository. Open a command prompt and change directory to the Smuthi project folder and enter:
python -m pip install -e .
If that command fails (e.g. because pip tries to compile the extension modules with the MSVC compiler instead of mingw), you can try:
python -m pip install wheel
python -m pip install numpy
python setup.py develop
Depending on the Python version, the above commands may fail to create statically linked extensions. This will lead to runtime errors saying that some DLL cannot be found. In that case you can try to overwrite the extension modules statically linked PYD-files by running the command:
python setup.py build_ext --inplace --compiler=mingw32 --fcompiler=gnu95 -f
Installing Smuthi from source on Windows can be troublesome. If you experience difficulties, please seek support from the Smuthi mailing list or open an issue on the Smuthi GitLab repository.
Verification¶
After installation from source you can check the unit tests:
Ubuntu:
sudo python3 -m pip install nose2
nose2
Windows:
python -m pip install nose2
nose2
GPU-acceleration (optional)¶
Note
PyCuda support is recommended if you run heavy simulations with many particles. In addition, it can speed up certain post processing steps like the evaluation of the electric field on a grid of points, e.g. when you create images of the field distribution. For simple simiulations involving one particle on a substrate, you might well go without.
If you want to benefit from fast simulations on the GPU, you need:
- A CUDA-capable NVIDIA GPU
- The NVIDIA CUDA toolkit installed
- PyCuda installed
Under Ubuntu, install PyCuda simply by:
sudo python3 -m pip install pycuda
Under Windows, installing PyCuda this is not as straightforward as under Linux. There exist prebuilt binaries on Christoph Gohlke’s homepage. See for example these instructions for the necessary steps to get it running.